home *** CD-ROM | disk | FTP | other *** search
/ Risc World 5 / Risc World 5.iso / SOFTWARE / Issue6 / VICE / VICE.ZIP / doc / vice_9 < prev    next >
Text File  |  2005-01-24  |  15KB  |  468 lines
  1. <HTML>
  2. <HEAD>
  3. <!-- This HTML file has been created by texi2html 1.52
  4.      from ../vice.texi on 23 January 2005 -->
  5.  
  6. <TITLE>VICE Manual - 9  Monitor</TITLE>
  7. </HEAD>
  8. <BODY>
  9. Go to the <A HREF="vice_1.html">first</A>, <A HREF="vice_8.html">previous</A>, <A HREF="vice_10.html">next</A>, <A HREF="vice_16.html">last</A> section, <A HREF="vice_toc.html">table of contents</A>.
  10. <P><HR><P>
  11.  
  12.  
  13. <H1><A NAME="SEC136" HREF="vice_toc.html#TOC136">9  Monitor</A></H1>
  14.  
  15. <P>
  16. Every VICE emulator has a complete built-in monitor, which can be used
  17. to examine, disassemble and assemble machine language programs, as
  18. well as debug them through breakpoints.  It can be activated by using
  19. the "Activate monitor" command (left button menu).  Notice that you
  20. have to run the emulator from a terminal emulation program (such as
  21. <CODE>rxvt</CODE> or <CODE>xterm</CODE>) in order to use the monitor.
  22.  
  23. </P>
  24. <P>
  25. <B>Warning</B>: this version of the monitor is still under construction,
  26. and some of the features are not fully working yet.
  27.  
  28. </P>
  29.  
  30.  
  31.  
  32. <H2><A NAME="SEC137" HREF="vice_toc.html#TOC137">9.1  Terminology</A></H2>
  33.  
  34. <DL COMPACT>
  35.  
  36. <DT><SAMP>`address_space'</SAMP>
  37. <DD>
  38. This refers to the range of memory locations and a set of registers.
  39. This can be the addresses available to the computer's processor, the
  40. disk drive's processor or a specific memory configuration of one of
  41. the mentioned processors.
  42.  
  43. <DT><SAMP>`bankname'</SAMP>
  44. <DD>
  45. The CPU can only see 64k of memory at any one time, due to its 16 bit
  46. address bus. The C64 and other computers have more than this amount,
  47. and this is handled by banking: a memory address can have different
  48. contents, depending on the active memory bank. 
  49. A bankname names a specific bank in the current address_space.
  50.  
  51. <DT><SAMP>`register'</SAMP>
  52. <DD>
  53. One of the following: program counter (PC), stack pointer (SP),
  54. accumulator (A), X register (X), or Y register (Y).
  55.  
  56. <DT><SAMP>`address'</SAMP>
  57. <DD>
  58. A specific memory location in the range $0000 to $FFFF.
  59.  
  60. <DT><SAMP>`address_range'</SAMP>
  61. <DD>
  62. Two addresses.  If the second address is less than the first, the
  63. range is assumed to wraparound from $FFFF to $0000.  Both addresses
  64. must be in the same address space.
  65.  
  66. <DT><SAMP>`address_opt_range'</SAMP>
  67. <DD>
  68. An address or an address range.
  69.  
  70. <DT><SAMP>`prompt'</SAMP>
  71. <DD>
  72. The prompt has the format [x:y].  If x is -, memory reads from the
  73. monitor do not have side effects.  Otherwise, x is S.  The second part
  74. of the prompt, y, shows the default address space.
  75.  
  76. <DT><SAMP>`checkpoint'</SAMP>
  77. <DD>
  78. The monitor has the ability to setup triggers that perform an action
  79. when a specified situation occurs.  There are three types of
  80. checkpoints; breakpoints, tracepoints and watchpoints.
  81.  
  82. <DT><SAMP>`breakpoint'</SAMP>
  83. <DD>
  84. A breakpoint is triggered based on the program counter.  When it is
  85. triggered, the monitor is entered.
  86.  
  87. <DT><SAMP>`tracepoint'</SAMP>
  88. <DD>
  89. Like breakpoints, a tracepoint is triggered based on the program
  90. counter.  Instead of entering the monitor, the program counter is
  91. printed and execution continues.
  92.  
  93. <DT><SAMP>`watchpoint'</SAMP>
  94. <DD>
  95. Watchpoints are triggered by a read and/or write to an address.  When
  96. a watchpoint is triggered, the monitor is entered.
  97.  
  98. <DT><SAMP>`<...>'</SAMP>
  99. <DD>
  100. A data type.
  101.  
  102. <DT><SAMP>`*'</SAMP>
  103. <DD>
  104. Zero or more occurrences.
  105.  
  106. <DT><SAMP>`[...]'</SAMP>
  107. <DD>
  108. An optional argument.
  109.  
  110. </DL>
  111.  
  112.  
  113.  
  114. <H2><A NAME="SEC138" HREF="vice_toc.html#TOC138">9.2  Machine state commands</A></H2>
  115.  
  116. <DL COMPACT>
  117.  
  118. <DT><CODE>goto <address></CODE>
  119. <DD>
  120. Change the PC to address and continue execution.
  121.  
  122. <DT><CODE>io</CODE>
  123. <DD>
  124. Nothing yet.  Will display VIC/VIA/CIA/SID registers.
  125.  
  126. <DT><CODE>next [<count>]</CODE>
  127. <DD>
  128. Advance to the next instruction.  Subroutines are treated as a single
  129. instruction.
  130.  
  131. <DT><CODE>registers [<reg_name> = <number> [, <reg_name> = <number>]*]</CODE>
  132. <DD>
  133. Assign respective registers.  With no parameters, display register
  134. values.
  135.  
  136. <DT><CODE>return</CODE>
  137. <DD>
  138. Continues execution  and returns to the monitor just
  139. after the next RTS or RTI is executed.
  140.  
  141. <DT><CODE>step [<count>]</CODE>
  142. <DD>
  143. Single step through instructions.  An optional count allows stepping
  144. more than a single instruction at a time.
  145.  
  146. </DL>
  147.  
  148.  
  149.  
  150. <H2><A NAME="SEC139" HREF="vice_toc.html#TOC139">9.3  Memory commands</A></H2>
  151.  
  152. <DL COMPACT>
  153.  
  154. <DT><CODE>bank [<bankname>]</CODE>
  155. <DD>
  156. Without a bankname, display all available banks for the current
  157. address_space. With a bankname given, switch to the specified
  158. bank. If a bank is not completely filled (ROM banks for example)
  159. normally the <CODE>ram</CODE> bank is used where the bank has holes.
  160. The <CODE>cpu</CODE> bank uses the bank currently used by the CPU.
  161.  
  162. <DT><CODE>compare <address_range> <address></CODE>
  163. <DD>
  164. Compare memory from the source specified by the address range to the
  165. destination specified by the address.  The regions may overlap.  Any
  166. values that miscompare are displayed using the default displaytype.
  167.  
  168. <DT><CODE>device [c:|8:|9:]</CODE>
  169. <DD>
  170. Set the default address space to either the computer `c:' or the
  171. specified drive `8:' or `9:'
  172. <DT><CODE>fill <address_range> <data_list></CODE>
  173. <DD>
  174. Fill memory in the specified address range with the data in
  175. <data_list>.  If the size of the address range is greater than the
  176. size of the data_list, the data_list is repeated.
  177.  
  178. <DT><CODE>hunt <address_range> <data_list></CODE>
  179. <DD>
  180. Hunt memory in the specified address range for the data in
  181. <data_list>.  If the data is found, the starting address of the match
  182. is displayed.  The entire range is searched for all possible matches.
  183.  
  184. <DT><CODE>i <address_opt_range></CODE>
  185. <DD>
  186. Display memory contents as PETSCII text.
  187.  
  188. <DT><CODE>m [<data_type>] [<address_opt_range>]</CODE>
  189. <DD>
  190. Display the contents of memory.  If no datatype is given, the default
  191. is used.  If only one address is specified, the length of data
  192. displayed is based on the datatype.  If no addresses are given, the
  193. 'dot' address is used.
  194.  
  195. <DT><CODE>mc [<data_type>] [<address_opt_range>]</CODE>
  196. <DD>
  197. Display the contents of memory as character data.  If only one address
  198. is specified, only one character is displayed.  If no addresses are
  199. given, the "dot" address is used.
  200.  
  201. <DT><CODE>ms [<data_type>] [<address_opt_range>]</CODE>
  202. <DD>
  203. Display the contents of memory as sprite data.  If only one address is
  204. specified, only one sprite is displayed.  If no addresses are given,
  205. the "dot" address is used.
  206.  
  207. <DT><CODE>move <address_range> <address></CODE>
  208. <DD>
  209. Move memory from the source specified by the address range to the
  210. destination specified by the address.  The regions may overlap.
  211.  
  212. <DT><CODE>sidefx [on|off|toggle]</CODE>
  213. <DD>
  214. Control how monitor generated reads affect memory locations that have
  215. read side-effects, like CIA interrupt registers for example.  
  216. If the argument is 'on' then reads may cause side-effects.  If the
  217. argument is 'off' then reads don't cause side-effects.  If the
  218. argument is 'toggle' then the current mode is switched.  No argument
  219. displays the current state.
  220.  
  221. <DT><CODE>> [<address>] <data_list></CODE>
  222. <DD>
  223. Write the specified data at <CODE>address</CODE>.
  224.  
  225. </DL>
  226.  
  227.  
  228.  
  229. <H2><A NAME="SEC140" HREF="vice_toc.html#TOC140">9.4  Assembly commands</A></H2>
  230.  
  231. <DL COMPACT>
  232.  
  233. <DT><CODE>a <address> [ <instruction> [: <instruction>]* ]</CODE>
  234. <DD>
  235. Assemble instructions to the specified address.  If only one
  236. instruction is specified, enter assembly mode (enter an empty line to
  237. exit assembly mode).
  238.  
  239. <DT><CODE>d [<address> [<address>]]</CODE>
  240. <DD>
  241. Disassemble instructions.  If two addresses are specified, they are
  242. used as a start and end address.  If only one is specified, it is
  243. treated as the start address and a default number of instructions are
  244. disassembled.  If no addresses are specified, a default number of
  245. instructions are disassembled from the dot address.
  246.  
  247. </DL>
  248.  
  249.  
  250.  
  251. <H2><A NAME="SEC141" HREF="vice_toc.html#TOC141">9.5  Checkpoint commands</A></H2>
  252.  
  253. <DL COMPACT>
  254.  
  255. <DT><CODE>break [<address> [if <cond_expr>] ]</CODE>
  256. <DD>
  257. This command allows setting a breakpoint or listing the current
  258. breakpoints.  If no address is given, the currently valid checkpoints
  259. are printed.  If an address is given, a breakpoint is set for that
  260. address and the breakpoint number is printed.  A conditional
  261. expression can also be specified for the breakpoint.  For more
  262. information on conditions, see the CONDITION command.
  263.  
  264. <DT><CODE>enable <checknum></CODE>
  265. <DD>
  266. <DT><CODE>disable <checknum></CODE>
  267. <DD>
  268. Each checkpoint can be enabled or disabled.  This command allows
  269. changing between these states.
  270.  
  271. <DT><CODE>command <checknum> "<command>"</CODE>
  272. <DD>
  273. When checkpoint <CODE>checknum</CODE> is hit, the specified command is
  274. executed by the monitor.  Note that the <CODE>x</CODE> command is not yet
  275. supported as a command argument.
  276.  
  277. <DT><CODE>condition <checknum> if <cond_expr></CODE>
  278. <DD>
  279. Each time the specified checkpoint is examined, the condition is
  280. evaluated.  If it evalutes to true, the checkpoint is activated.
  281. Otherwise, it is ignores.  If registers are specified in the
  282. expression, the values used are those at the time the checkpoint is
  283. examined, not when the condition is set.
  284.  
  285. <DT><CODE>delete <checknum></CODE>
  286. <DD>
  287. Delete the specified checkpoint.
  288.  
  289. <DT><CODE>ignore <checknum> [<count>]</CODE>
  290. <DD>
  291. Ignore a checkpoint after a given number of crossings.  If no count is
  292. given, the default value is 1.
  293.  
  294. <DT><CODE>trace [address [address]]</CODE>
  295. <DD>
  296. This command is similar to the <CODE>break</CODE> command except that it
  297. operates on tracepoints.  A tracepoint differs from a breakpoint by
  298. not stopping execution but simply printing the PC, giving the user an
  299. execution trace.  The second optional address can be used to specify
  300. the end of an range of addresses to be traced.
  301.  
  302. <DT><CODE>watch [loadstore] [address [address]]</CODE>
  303. <DD>
  304. This command is similar to the previous two commands except that it
  305. operates on watchpoints.  A watchpoint differs from the others by
  306. stopping on a read and/or write to an address or range of addresses.
  307. If no addresses are given, a list of all the watchpoints is printed.
  308. The loadstore parameter can be either "load" or "store" to determine
  309. on which operation the monitor breaks. If not specified, the monitor
  310. breaks on both operations.
  311.  
  312. </DL>
  313.  
  314.  
  315.  
  316. <H2><A NAME="SEC142" HREF="vice_toc.html#TOC142">9.6  General commands</A></H2>
  317.  
  318. <DL COMPACT>
  319.  
  320. <DT><CODE>cd <directory></CODE>
  321. <DD>
  322. Change the working directory.
  323.  
  324. <DT><CODE>device [c:|d:]</CODE>
  325. <DD>
  326. Set the default memory device to either the computer (<CODE>c:</CODE>) or
  327. the disk (<CODE>d:</CODE>).
  328.  
  329. <DT><CODE>radix [H|D|O|B]</CODE>
  330. <DD>
  331. Set the default radix to hex, decimal, octal, or binary.  With no
  332. argument, the current radix is printed.
  333.  
  334. <DT><CODE>sidefx [on|off|toggle]</CODE>
  335. <DD>
  336. Control how monitor generated reads affect memory locations that have
  337. read side-effects.  If the argument is 'on' then reads may cause
  338. side-effects.  If the argument is 'off' then reads don't cause
  339. side-effects.  If the argument is 'toggle' then the current mode is
  340. switched.  No argument displays the current state.
  341.  
  342. <DT><CODE>system <system command></CODE>
  343. <DD>
  344. Nothing yet.
  345.  
  346. </DL>
  347.  
  348.  
  349.  
  350. <H2><A NAME="SEC143" HREF="vice_toc.html#TOC143">9.7  Disk commands</A></H2>
  351.  
  352. <DL COMPACT>
  353.  
  354. <DT><CODE>br <track> <sector> [<address>]</CODE>
  355. <DD>
  356. Read the block at the specified track and sector.  If an address is
  357. specified, the data is loaded into memory.  If no address is given,
  358. the data is displayed using the default datatype.
  359.  
  360. <DT><CODE>bw <track> <sector> <address></CODE>
  361. <DD>
  362. Write a block of data at <CODE>address</CODE> to the specified track and
  363. sector of disk in drive 8.
  364.  
  365. <DT><CODE>@<disk command></CODE>
  366. <DD>
  367. Perform a disk command on the currently attached disk image on drive
  368. 8.  The specified disk command is sent to the drive's channel #15.
  369.  
  370. <DT><CODE>load "<filename>" <device> [<address>]</CODE>
  371. <DD>
  372. Load the specified file into memory.  If no address is given, the file
  373. is loaded to the address specified by the first two bytes read from
  374. the file.  If address is given, the file is loaded to the specified
  375. address and the first two bytes read from the file are skipped.  If
  376. device is 0, the file is read from the file system.
  377.  
  378. <DT><CODE>save "<filename>" <device> <address1> <address2></CODE>
  379. <DD>
  380. Save the memory from address1 to address2 to the specified file.  If
  381. device is 0, the file is written to the file system.
  382.  
  383. </DL>
  384.  
  385.  
  386.  
  387. <H2><A NAME="SEC144" HREF="vice_toc.html#TOC144">9.8  Command file commands</A></H2>
  388.  
  389. <DL COMPACT>
  390.  
  391. <DT><CODE>playback "<filename>"</CODE>
  392. <DD>
  393. Monitor commands from the specified file are read and executed.  This
  394. command stops at the end of file or when a STOP command is read.
  395.  
  396. <DT><CODE>record "<filename>"</CODE>
  397. <DD>
  398. After this command, all commands entered are written to the specified
  399. file until the STOP command is entered.
  400.  
  401. <DT><CODE>stop</CODE>
  402. <DD>
  403. Stop recording commands.  See <CODE>record</CODE>.
  404.  
  405. </DL>
  406.  
  407.  
  408.  
  409. <H2><A NAME="SEC145" HREF="vice_toc.html#TOC145">9.9  Label commands</A></H2>
  410.  
  411. <DL COMPACT>
  412.  
  413. <DT><CODE>add_label <address> <label></CODE>
  414. <DD>
  415. Map a given address to a label.  This label can be used when entering
  416. assembly code and is shown during disassembly.
  417.  
  418. <DT><CODE>delete_label [<memspace>] <label></CODE>
  419. <DD>
  420. Remove the specified label from the label tables.  If no memory space is
  421. checked, all tables are checked.
  422.  
  423. <DT><CODE>load_labels [<memspace>] "<filename>"</CODE>
  424. <DD>
  425. Load a file containing a mapping of labels to addresses.  If no memory
  426. space is specified, the default readspace is used.
  427.  
  428. <DT><CODE>save_labels [<memspace>] "<filename>"</CODE>
  429. <DD>
  430. Save labels to a file.  If no memory space is specified, all of the
  431. labels are saved.
  432.  
  433. <DT><CODE>show_labels [<memspace>]</CODE>
  434. <DD>
  435. Display current label mappings.  If no memory space is specified, show
  436. all labels.
  437.  
  438. </DL>
  439.  
  440.  
  441.  
  442. <H2><A NAME="SEC146" HREF="vice_toc.html#TOC146">9.10  Miscellaneous commands</A></H2>
  443.  
  444. <DL COMPACT>
  445.  
  446. <DT><CODE>exit</CODE>
  447. <DD>
  448. Leave the monitor and return to execution.
  449.  
  450. <DT><CODE>print <expression></CODE>
  451. <DD>
  452. Evaluate the specified expression and output the result.
  453.  
  454. <DT><CODE>quit</CODE>
  455. <DD>
  456. Exit the emulator immediately.
  457.  
  458. <DT><CODE>~ <number></CODE>
  459. <DD>
  460. Display the specified number in decimal, hex, octal and binary.
  461.  
  462. </DL>
  463.  
  464. <P><HR><P>
  465. Go to the <A HREF="vice_1.html">first</A>, <A HREF="vice_8.html">previous</A>, <A HREF="vice_10.html">next</A>, <A HREF="vice_16.html">last</A> section, <A HREF="vice_toc.html">table of contents</A>.
  466. </BODY>
  467. </HTML>
  468.